home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / dppsvx.z / dppsvx
Text File  |  1996-03-14  |  11KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))                                                          DDDDPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DPPSVX - use the Cholesky factorization A = U**T*U or A = L*L**T to
  10.      compute the solution to a real system of linear equations  A * X = B,
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE DPPSVX( FACT, UPLO, N, NRHS, AP, AFP, EQUED, S, B, LDB, X,
  14.                         LDX, RCOND, FERR, BERR, WORK, IWORK, INFO )
  15.  
  16.          CHARACTER      EQUED, FACT, UPLO
  17.  
  18.          INTEGER        INFO, LDB, LDX, N, NRHS
  19.  
  20.          DOUBLE         PRECISION RCOND
  21.  
  22.          INTEGER        IWORK( * )
  23.  
  24.          DOUBLE         PRECISION AFP( * ), AP( * ), B( LDB, * ), BERR( * ),
  25.                         FERR( * ), S( * ), WORK( * ), X( LDX, * )
  26.  
  27. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  28.      DPPSVX uses the Cholesky factorization A = U**T*U or A = L*L**T to
  29.      compute the solution to a real system of linear equations
  30.         A * X = B, where A is an N-by-N symmetric positive definite matrix
  31.      stored in packed format and X and B are N-by-NRHS matrices.
  32.  
  33.      Error bounds on the solution and a condition estimate are also provided.
  34.  
  35.  
  36. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  37.      The following steps are performed:
  38.  
  39.      1. If FACT = 'E', real scaling factors are computed to equilibrate
  40.         the system:
  41.            diag(S) * A * diag(S) * inv(diag(S)) * X = diag(S) * B
  42.         Whether or not the system will be equilibrated depends on the
  43.         scaling of the matrix A, but if equilibration is used, A is
  44.         overwritten by diag(S)*A*diag(S) and B by diag(S)*B.
  45.  
  46.      2. If FACT = 'N' or 'E', the Cholesky decomposition is used to
  47.         factor the matrix A (after equilibration if FACT = 'E') as
  48.            A = U**T* U,  if UPLO = 'U', or
  49.            A = L * L**T,  if UPLO = 'L',
  50.         where U is an upper triangular matrix and L is a lower triangular
  51.         matrix.
  52.  
  53.      3. The factored form of A is used to estimate the condition number
  54.         of the matrix A.  If the reciprocal of the condition number is
  55.         less than machine precision, steps 4-6 are skipped.
  56.  
  57.      4. The system of equations is solved for X using the factored form
  58.         of A.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))                                                          DDDDPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))
  71.  
  72.  
  73.  
  74.      5. Iterative refinement is applied to improve the computed solution
  75.         matrix and calculate error bounds and backward error estimates
  76.         for it.
  77.  
  78.      6. If equilibration was used, the matrix X is premultiplied by
  79.         diag(S) so that it solves the original system before
  80.         equilibration.
  81.  
  82.  
  83. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  84.      FACT    (input) CHARACTER*1
  85.              Specifies whether or not the factored form of the matrix A is
  86.              supplied on entry, and if not, whether the matrix A should be
  87.              equilibrated before it is factored.  = 'F':  On entry, AFP
  88.              contains the factored form of A.  If EQUED = 'Y', the matrix A
  89.              has been equilibrated with scaling factors given by S.  AP and
  90.              AFP will not be modified.  = 'N':  The matrix A will be copied to
  91.              AFP and factored.
  92.              = 'E':  The matrix A will be equilibrated if necessary, then
  93.              copied to AFP and factored.
  94.  
  95.      UPLO    (input) CHARACTER*1
  96.              = 'U':  Upper triangle of A is stored;
  97.              = 'L':  Lower triangle of A is stored.
  98.  
  99.      N       (input) INTEGER
  100.              The number of linear equations, i.e., the order of the matrix A.
  101.              N >= 0.
  102.  
  103.      NRHS    (input) INTEGER
  104.              The number of right hand sides, i.e., the number of columns of
  105.              the matrices B and X.  NRHS >= 0.
  106.  
  107.      AP      (input/output) DOUBLE PRECISION array, dimension (N*(N+1)/2)
  108.              On entry, the upper or lower triangle of the symmetric matrix A,
  109.              packed columnwise in a linear array, except if FACT = 'F' and
  110.              EQUED = 'Y', then A must contain the equilibrated matrix
  111.              diag(S)*A*diag(S).  The j-th column of A is stored in the array
  112.              AP as follows:  if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for
  113.              1<=i<=j; if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for
  114.              j<=i<=n.  See below for further details.  A is not modified if
  115.              FACT = 'F' or 'N', or if FACT = 'E' and EQUED = 'N' on exit.
  116.  
  117.              On exit, if FACT = 'E' and EQUED = 'Y', A is overwritten by
  118.              diag(S)*A*diag(S).
  119.  
  120.      AFP     (input or output) DOUBLE PRECISION array, dimension
  121.              (N*(N+1)/2) If FACT = 'F', then AFP is an input argument and on
  122.              entry contains the triangular factor U or L from the Cholesky
  123.              factorization A = U'*U or A = L*L', in the same storage format as
  124.              A.  If EQUED .ne. 'N', then AFP is the factored form of the
  125.              equilibrated matrix A.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))                                                          DDDDPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))
  137.  
  138.  
  139.  
  140.              If FACT = 'N', then AFP is an output argument and on exit returns
  141.              the triangular factor U or L from the Cholesky factorization A =
  142.              U'*U or A = L*L' of the original matrix A.
  143.  
  144.              If FACT = 'E', then AFP is an output argument and on exit returns
  145.              the triangular factor U or L from the Cholesky factorization A =
  146.              U'*U or A = L*L' of the equilibrated matrix A (see the
  147.              description of AP for the form of the equilibrated matrix).
  148.  
  149.      EQUED   (input or output) CHARACTER*1
  150.              Specifies the form of equilibration that was done.  = 'N':  No
  151.              equilibration (always true if FACT = 'N').
  152.              = 'Y':  Equilibration was done, i.e., A has been replaced by
  153.              diag(S) * A * diag(S).  EQUED is an input argument if FACT = 'F';
  154.              otherwise, it is an output argument.
  155.  
  156.      S       (input or output) DOUBLE PRECISION array, dimension (N)
  157.              The scale factors for A; not accessed if EQUED = 'N'.  S is an
  158.              input argument if FACT = 'F'; otherwise, S is an output argument.
  159.              If FACT = 'F' and EQUED = 'Y', each element of S must be
  160.              positive.
  161.  
  162.      B       (input/output) DOUBLE PRECISION array, dimension (LDB,NRHS)
  163.              On entry, the N-by-NRHS right hand side matrix B.  On exit, if
  164.              EQUED = 'N', B is not modified; if EQUED = 'Y', B is overwritten
  165.              by diag(S) * B.
  166.  
  167.      LDB     (input) INTEGER
  168.              The leading dimension of the array B.  LDB >= max(1,N).
  169.  
  170.      X       (output) DOUBLE PRECISION array, dimension (LDX,NRHS)
  171.              If INFO = 0, the N-by-NRHS solution matrix X to the original
  172.              system of equations.  Note that if EQUED = 'Y', A and B are
  173.              modified on exit, and the solution to the equilibrated system is
  174.              inv(diag(S))*X.
  175.  
  176.      LDX     (input) INTEGER
  177.              The leading dimension of the array X.  LDX >= max(1,N).
  178.  
  179.      RCOND   (output) DOUBLE PRECISION
  180.              The estimate of the reciprocal condition number of the matrix A
  181.              after equilibration (if done).  If RCOND is less than the machine
  182.              precision (in particular, if RCOND = 0), the matrix is singular
  183.              to working precision.  This condition is indicated by a return
  184.              code of INFO > 0, and the solution and error bounds are not
  185.              computed.
  186.  
  187.      FERR    (output) DOUBLE PRECISION array, dimension (NRHS)
  188.              The estimated forward error bound for each solution vector X(j)
  189.              (the j-th column of the solution matrix X).  If XTRUE is the true
  190.              solution corresponding to X(j), FERR(j) is an estimated upper
  191.              bound for the magnitude of the largest element in (X(j) - XTRUE)
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))                                                          DDDDPPPPPPPPSSSSVVVVXXXX((((3333FFFF))))
  203.  
  204.  
  205.  
  206.              divided by the magnitude of the largest element in X(j).  The
  207.              estimate is as reliable as the estimate for RCOND, and is almost
  208.              always a slight overestimate of the true error.
  209.  
  210.      BERR    (output) DOUBLE PRECISION array, dimension (NRHS)
  211.              The componentwise relative backward error of each solution vector
  212.              X(j) (i.e., the smallest relative change in any element of A or B
  213.              that makes X(j) an exact solution).
  214.  
  215.      WORK    (workspace) DOUBLE PRECISION array, dimension (3*N)
  216.  
  217.      IWORK   (workspace) INTEGER array, dimension (N)
  218.  
  219.      INFO    (output) INTEGER
  220.              = 0:  successful exit
  221.              < 0:  if INFO = -i, the i-th argument had an illegal value
  222.              > 0:  if INFO = i, and i is
  223.              <= N: the leading minor of order i of A is not positive definite,
  224.              so the factorization could not be completed, and the solution and
  225.              error bounds could not be computed.  = N+1: RCOND is less than
  226.              machine precision.  The factorization has been completed, but the
  227.              matrix is singular to working precision, and the solution and
  228.              error bounds have not been computed.
  229.  
  230. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  231.      The packed storage scheme is illustrated by the following example when N
  232.      = 4, UPLO = 'U':
  233.  
  234.      Two-dimensional storage of the symmetric matrix A:
  235.  
  236.         a11 a12 a13 a14
  237.             a22 a23 a24
  238.                 a33 a34     (aij = conjg(aji))
  239.                     a44
  240.  
  241.      Packed storage of the upper triangle of A:
  242.  
  243.      AP = [ a11, a12, a22, a13, a23, a33, a14, a24, a34, a44 ]
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.